Autogenerated HTML docs for v2.0.0-239-g09531
diff --git a/RelNotes/2.1.0.txt b/RelNotes/2.1.0.txt index ad53d0d..527b07e 100644 --- a/RelNotes/2.1.0.txt +++ b/RelNotes/2.1.0.txt
@@ -1,18 +1,61 @@ Git v2.1 Release Notes ====================== +Backward compatibility notes +---------------------------- + + * The default value we give to the environment variable LESS has been + changed from "FRSX" to "FRX", losing "S" (chop long lines instead + of wrapping). Existing users who prefer not to see line-wrapped + output may want to set + + $ git config core.pager "less -S" + + to restore the traditional behaviour. It is expected that people + find output from the most subcommands easier to read with the new + default, except for "blame" which tends to produce really long + lines. To override the new default only for "git blame", you can + do this: + + $ git config pager.blame "less -S" + + * A few disused directories in contrib/ have been retired. + + Updates since v2.0 ------------------ UI, Workflows & Features + * Since the very beginning of Git, we gave the LESS environment a + default value "FRSX" when we spawn "less" as the pager. "S" (chop + long lines instead of wrapping) has been removed from this default + set of options, because it is more or less a personal taste thing, + as opposed to others that have good justifications (i.e. "R" is + very much justified because many kinds of output we produce are + colored and "FX" is justified because output we produce is often + shorter than a page). + + * The logic and data used to compute the display width needed for + UTF-8 strings have been updated to match Unicode 6.3 better. + * "git commit --date=<date>" option learned to read from more timestamp formats, including "--date=now". + * The `core.commentChar` configuration variable is used to specify a + custom comment character other than the default "#" to be used in + the commit log editor. This can be set to `auto` to attempt to + choose a different character that does not conflict with what + already starts a line in the message being edited for cases like + "git commit --amend". + * "git grep" learned grep.fullname configuration variable to force "--full-name" to be default. This may cause regressions on scripted users that do not expect this new behaviour. + * "git imap-send" learned to ask the credential helper for auth + material. + * "git merge" without argument, even when there is an upstream defined for the current branch, refused to run until merge.defaultToUpstream is set to true. Flip the default of that @@ -37,9 +80,21 @@ digit in the hour part, e.g. 2014-01-07T5:01:02.048176Z, emitted by some broken subversion server implementations. + * "git tag" when editing the tag message shows the name of the tag + being edited as a comment in the editor. + Performance, Internal Implementation, etc. + * Build procedure for 'subtree' (in contrib/) has been cleaned up. + + * The `core.deltabasecachelimit` used to default to 16 MiB , but this + proved to be too small, and has been bumped to 96 MiB. + + * "git blame" has been optimized greatly by reorganising the data + structure that is used to keep track of the work to be done, thanks + to David Karstrup <dak@gnu.org>. + * "git diff" that compares 3-or-more trees (e.g. parents and the result of a merge) have been optimized. @@ -59,6 +114,11 @@ track are contained in this release (see the maintenance releases' notes for details). + * We used to unconditionally disable the pager in the pager process + we spawn to feed out output, but that prevented people who want to + run "less" within "less" from doing so. + (merge c0459ca je/pager-do-not-recurse later to maint). + * "--ignore-space-change" option of "git apply" ignored the spaces at the beginning of line too aggressively, which is inconsistent with the option of the same name "diff" and "git diff" have. @@ -69,15 +129,42 @@ lines in its output. (merge dd75553 jx/blame-align-relative-time later to maint). + * "git blame" assigned the blame to the copy in the working-tree if + the repository is set to core.autocrlf=input and the file used CRLF + line endings. + (merge 4d4813a bc/blame-crlf-test later to maint). + + * "git commit --allow-empty-messag -C $commit" did not work when the + commit did not have any log message. + (merge 076cbd6 jk/commit-C-pick-empty later to maint). + + * "git grep -O" to show the lines that hit in the pager did not work + well with case insensitive search. We now spawn "less" with its + "-I" option when it is used as the pager (which is the default). + (merge f7febbe sk/spawn-less-case-insensitively-from-grep-O-i later to maint). + * We used to disable threaded "git index-pack" on platforms without thread-safe pread(); use a different workaround for such platforms to allow threaded "git index-pack". (merge 3953949 nd/index-pack-one-fd-per-thread later to maint). + * The error reporting from "git index-pack" has been improved to + distinguish missing objects from type errors. + (merge 77583e7 jk/index-pack-report-missing later to maint). + + * On a case insensitive filesystem, merge-recursive incorrectly + deleted the file that is to be renamed to a name that is the same + except for case differences. + (merge baa37bf dt/merge-recursive-case-insensitive later to maint). + * "git rerere forget" did not work well when merge.conflictstyle was set to a non-default value. (merge de3d8bb fc/rerere-conflict-style later to maint). + * "git show -s" (i.e. show log message only) used to incorrectly emit + an extra blank line after a merge commit. + (merge ad2f725 mk/show-s-no-extra-blank-line-for-merges later to maint). + * "git status", even though it is a read-only operation, tries to update the index with refreshed lstat(2) info to optimize future accesses to the working tree opportunistically, but this could
diff --git a/config.txt b/config.txt index 1932e9b..cd2d651 100644 --- a/config.txt +++ b/config.txt
@@ -381,7 +381,7 @@ core.worktree:: Set the path to the root of the working tree. This can be overridden by the GIT_WORK_TREE environment - variable and the '--work-tree' command line option. + variable and the '--work-tree' command-line option. The value can be an absolute path or relative to the path to the .git directory, which is either specified by --git-dir or GIT_DIR, or automatically discovered. @@ -489,7 +489,7 @@ to avoid unpacking and decompressing frequently used base objects multiple times. + -Default is 16 MiB on all platforms. This should be reasonable +Default is 96 MiB on all platforms. This should be reasonable for all users/operating systems, except on the largest projects. You probably do not need to adjust this value. + @@ -523,7 +523,7 @@ environment variable. If not set, fall back to the value of the 'SSH_ASKPASS' environment variable or, failing that, a simple password prompt. The external program shall be given a suitable prompt as - command line argument and write the password on its STDOUT. + command-line argument and write the password on its STDOUT. core.attributesfile:: In addition to '.gitattributes' (per-directory) and @@ -544,6 +544,9 @@ messages consider a line that begins with this character commented, and removes them after the editor returns (default '#'). ++ +If set to "auto", `git-commit` would select a character that is not +the beginning character of any line in existing commit messages. sequence.editor:: Text editor used by `git rebase -i` for editing the rebase instruction file. @@ -558,14 +561,19 @@ configuration, then `$PAGER`, and then the default chosen at compile time (usually 'less'). + -When the `LESS` environment variable is unset, Git sets it to `FRSX` +When the `LESS` environment variable is unset, Git sets it to `FRX` (if `LESS` environment variable is set, Git does not change it at all). If you want to selectively override Git's default setting -for `LESS`, you can set `core.pager` to e.g. `less -+S`. This will +for `LESS`, you can set `core.pager` to e.g. `less -S`. This will be passed to the shell by Git, which will translate the final -command to `LESS=FRSX less -+S`. The environment tells the command -to set the `S` option to chop long lines but the command line -resets it to the default to fold long lines. +command to `LESS=FRX less -S`. The environment does not set the +`S` option but the command line does, instructing less to truncate +long lines. Similarly, setting `core.pager` to `less -+F` will +deactivate the `F` option specified by the environment from the +command-line, deactivating the "quit if one screen" behavior of +`less`. One can specifically activate some flags for particular +commands: for example, setting `pager.blame` to `less -S` enables +line truncation only for `git blame`. + Likewise, when the `LV` environment variable is unset, Git sets it to `-c`. You can override this setting by exporting `LV` with @@ -1324,7 +1332,7 @@ gpg.program:: Use this custom program instead of "gpg" found on $PATH when making or verifying a PGP signature. The program must support the - same command line interface as GPG, namely, to verify a detached + same command-line interface as GPG, namely, to verify a detached signature, "gpg --verify $file - <$signature" is run, and the program is expected to signal a good signature by exiting with code 0, and to generate an ascii-armored detached signature, the @@ -2295,7 +2303,7 @@ submodules when `diff.ignoreSubmodules` is set to 'all' or only for those submodules where `submodule.<name>.ignore=all`. To also view the summary for ignored submodules you can either use - the --ignore-submodules=dirty command line option or the 'git + the --ignore-submodules=dirty command-line option or the 'git submodule summary' command, which shows a similar output but does not honor these settings. @@ -2317,7 +2325,7 @@ submodule.<name>.fetchRecurseSubmodules:: This option can be used to control recursive fetching of this submodule. It can be overridden by using the --[no-]recurse-submodules - command line option to "git fetch" and "git pull". + command-line option to "git fetch" and "git pull". This setting will override that from in the linkgit:gitmodules[5] file.
diff --git a/diff-config.txt b/diff-config.txt index f07b451..b001779 100644 --- a/diff-config.txt +++ b/diff-config.txt
@@ -76,7 +76,7 @@ this setting when reporting uncommitted changes. Setting it to 'all' disables the submodule summary normally shown by 'git commit' and 'git status' when 'status.submodulesummary' is set unless it is - overridden by using the --ignore-submodules command line option. + overridden by using the --ignore-submodules command-line option. The 'git submodule' commands are not affected by this setting. diff.mnemonicprefix::
diff --git a/git-bisect.html b/git-bisect.html index 8f7efa9..df7e27a 100644 --- a/git-bisect.html +++ b/git-bisect.html
@@ -848,7 +848,7 @@ </div></div> <div class="paragraph"><p><tt>view</tt> may also be used as a synonym for <tt>visualize</tt>.</p></div> <div class="paragraph"><p>If the <em>DISPLAY</em> environment variable is not set, <em>git log</em> is used -instead. You can also give command line options such as <tt>-p</tt> and +instead. You can also give command-line options such as <tt>-p</tt> and <tt>--stat</tt>.</p></div> <div class="listingblock"> <div class="content"> @@ -1131,7 +1131,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2013-08-20 08:40:27 PDT +Last updated 2014-06-06 12:15:38 PDT </div> </div> </body>
diff --git a/git-bisect.txt b/git-bisect.txt index f986c5c..4cb52a7 100644 --- a/git-bisect.txt +++ b/git-bisect.txt
@@ -117,7 +117,7 @@ `view` may also be used as a synonym for `visualize`. If the 'DISPLAY' environment variable is not set, 'git log' is used -instead. You can also give command line options such as `-p` and +instead. You can also give command-line options such as `-p` and `--stat`. ------------
diff --git a/git-config.html b/git-config.html index 20e1897..d6dec62 100644 --- a/git-config.html +++ b/git-config.html
@@ -1171,7 +1171,7 @@ <div class="paragraph"><p>All writing options will per default write to the repository specific configuration file. Note that this also affects options like <em>--replace-all</em> and <em>--unset</em>. <strong><em>git config</em> will only ever change one file at a time</strong>.</p></div> -<div class="paragraph"><p>You can override these rules either by command line options or by environment +<div class="paragraph"><p>You can override these rules either by command-line options or by environment variables. The <em>--global</em> and the <em>--system</em> options will limit the file used to the global or system-wide file respectively. The GIT_CONFIG environment variable has a similar effect, but you can specify any filename you want.</p></div> @@ -1860,7 +1860,7 @@ <p> Set the path to the root of the working tree. This can be overridden by the GIT_WORK_TREE environment - variable and the <em>--work-tree</em> command line option. + variable and the <em>--work-tree</em> command-line option. The value can be an absolute path or relative to the path to the .git directory, which is either specified by --git-dir or GIT_DIR, or automatically discovered. @@ -2006,7 +2006,7 @@ to avoid unpacking and decompressing frequently used base objects multiple times. </p> -<div class="paragraph"><p>Default is 16 MiB on all platforms. This should be reasonable +<div class="paragraph"><p>Default is 96 MiB on all platforms. This should be reasonable for all users/operating systems, except on the largest projects. You probably do not need to adjust this value.</p></div> <div class="paragraph"><p>Common unit suffixes of <em>k</em>, <em>m</em>, or <em>g</em> are supported.</p></div> @@ -2051,7 +2051,7 @@ environment variable. If not set, fall back to the value of the <em>SSH_ASKPASS</em> environment variable or, failing that, a simple password prompt. The external program shall be given a suitable prompt as - command line argument and write the password on its STDOUT. + command-line argument and write the password on its STDOUT. </p> </dd> <dt class="hdlist1"> @@ -2088,6 +2088,8 @@ commented, and removes them after the editor returns (default <em>#</em>). </p> +<div class="paragraph"><p>If set to "auto", <tt>git-commit</tt> would select a character that is not +the beginning character of any line in existing commit messages.</p></div> </dd> <dt class="hdlist1"> sequence.editor @@ -2111,14 +2113,19 @@ configuration, then <tt>$PAGER</tt>, and then the default chosen at compile time (usually <em>less</em>). </p> -<div class="paragraph"><p>When the <tt>LESS</tt> environment variable is unset, Git sets it to <tt>FRSX</tt> +<div class="paragraph"><p>When the <tt>LESS</tt> environment variable is unset, Git sets it to <tt>FRX</tt> (if <tt>LESS</tt> environment variable is set, Git does not change it at all). If you want to selectively override Git’s default setting -for <tt>LESS</tt>, you can set <tt>core.pager</tt> to e.g. <tt>less -+S</tt>. This will +for <tt>LESS</tt>, you can set <tt>core.pager</tt> to e.g. <tt>less -S</tt>. This will be passed to the shell by Git, which will translate the final -command to <tt>LESS=FRSX less -+S</tt>. The environment tells the command -to set the <tt>S</tt> option to chop long lines but the command line -resets it to the default to fold long lines.</p></div> +command to <tt>LESS=FRX less -S</tt>. The environment does not set the +<tt>S</tt> option but the command line does, instructing less to truncate +long lines. Similarly, setting <tt>core.pager</tt> to <tt>less -+F</tt> will +deactivate the <tt>F</tt> option specified by the environment from the +command-line, deactivating the "quit if one screen" behavior of +<tt>less</tt>. One can specifically activate some flags for particular +commands: for example, setting <tt>pager.blame</tt> to <tt>less -S</tt> enables +line truncation only for <tt>git blame</tt>.</p></div> <div class="paragraph"><p>Likewise, when the <tt>LV</tt> environment variable is unset, Git sets it to <tt>-c</tt>. You can override this setting by exporting <tt>LV</tt> with another value or setting <tt>core.pager</tt> to <tt>lv +c</tt>.</p></div> @@ -3093,7 +3100,7 @@ this setting when reporting uncommitted changes. Setting it to <em>all</em> disables the submodule summary normally shown by <em>git commit</em> and <em>git status</em> when <em>status.submodulesummary</em> is set unless it is - overridden by using the --ignore-submodules command line option. + overridden by using the --ignore-submodules command-line option. The <em>git submodule</em> commands are not affected by this setting. </p> </dd> @@ -3991,7 +3998,7 @@ <p> Use this custom program instead of "gpg" found on $PATH when making or verifying a PGP signature. The program must support the - same command line interface as GPG, namely, to verify a detached + same command-line interface as GPG, namely, to verify a detached signature, "gpg --verify $file - <$signature" is run, and the program is expected to signal a good signature by exiting with code 0, and to generate an ascii-armored detached signature, the @@ -5981,7 +5988,7 @@ submodules when <tt>diff.ignoreSubmodules</tt> is set to <em>all</em> or only for those submodules where <tt>submodule.<name>.ignore=all</tt>. To also view the summary for ignored submodules you can either use - the --ignore-submodules=dirty command line option or the <em>git + the --ignore-submodules=dirty command-line option or the <em>git submodule summary</em> command, which shows a similar output but does not honor these settings. </p> @@ -6022,7 +6029,7 @@ <p> This option can be used to control recursive fetching of this submodule. It can be overridden by using the --[no-]recurse-submodules - command line option to "git fetch" and "git pull". + command-line option to "git fetch" and "git pull". This setting will override that from in the <a href="gitmodules.html">gitmodules(5)</a> file. </p> @@ -6231,7 +6238,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2013-09-09 15:34:20 PDT +Last updated 2014-06-06 12:15:38 PDT </div> </div> </body>
diff --git a/git-config.txt b/git-config.txt index e9917b8..9dfa1a5 100644 --- a/git-config.txt +++ b/git-config.txt
@@ -256,7 +256,7 @@ configuration file. Note that this also affects options like '--replace-all' and '--unset'. *'git config' will only ever change one file at a time*. -You can override these rules either by command line options or by environment +You can override these rules either by command-line options or by environment variables. The '--global' and the '--system' options will limit the file used to the global or system-wide file respectively. The GIT_CONFIG environment variable has a similar effect, but you can specify any filename you want.
diff --git a/git-daemon.html b/git-daemon.html index 79a1151..337bce5 100644 --- a/git-daemon.html +++ b/git-daemon.html
@@ -1019,7 +1019,7 @@ <p> Allow/forbid overriding the site-wide default with per repository configuration. By default, all the services - are overridable. + may be overridden. </p> </dd> <dt class="hdlist1"> @@ -1044,7 +1044,7 @@ Every time a client connects, first run an external command specified by the <path> with service name (e.g. "upload-pack"), path to the repository, hostname (%H), canonical hostname - (%CH), ip address (%IP), and tcp port (%P) as its command line + (%CH), IP address (%IP), and TCP port (%P) as its command-line arguments. The external command can decide to decline the service by exiting with a non-zero status (or to allow it by exiting with a zero status). It can also look at the $REMOTE_ADDR @@ -1072,7 +1072,7 @@ <h2 id="_services">SERVICES</h2> <div class="sectionbody"> <div class="paragraph"><p>These services can be globally enabled/disabled using the -command line options of this command. If a finer-grained +command-line options of this command. If finer-grained control is desired (e.g. to allow <em>git archive</em> to be run against only in a few selected repositories the daemon serves), the per-repository configuration file can be used to enable or @@ -1234,7 +1234,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2013-08-20 08:40:27 PDT +Last updated 2014-06-06 12:15:38 PDT </div> </div> </body>
diff --git a/git-daemon.txt b/git-daemon.txt index 223f731..a69b361 100644 --- a/git-daemon.txt +++ b/git-daemon.txt
@@ -169,7 +169,7 @@ --forbid-override=<service>:: Allow/forbid overriding the site-wide default with per repository configuration. By default, all the services - are overridable. + may be overridden. --[no-]informative-errors:: When informative errors are turned on, git-daemon will report @@ -184,7 +184,7 @@ Every time a client connects, first run an external command specified by the <path> with service name (e.g. "upload-pack"), path to the repository, hostname (%H), canonical hostname - (%CH), ip address (%IP), and tcp port (%P) as its command line + (%CH), IP address (%IP), and TCP port (%P) as its command-line arguments. The external command can decide to decline the service by exiting with a non-zero status (or to allow it by exiting with a zero status). It can also look at the $REMOTE_ADDR @@ -204,7 +204,7 @@ -------- These services can be globally enabled/disabled using the -command line options of this command. If a finer-grained +command-line options of this command. If finer-grained control is desired (e.g. to allow 'git archive' to be run against only in a few selected repositories the daemon serves), the per-repository configuration file can be used to enable or
diff --git a/git-fast-import.html b/git-fast-import.html index 8716428..d7662b3 100644 --- a/git-fast-import.html +++ b/git-fast-import.html
@@ -1057,7 +1057,7 @@ <h3 id="_date_formats">Date Formats</h3> <div class="paragraph"><p>The following date formats are supported. A frontend should select the format it will use for this import by passing the format name -in the --date-format=<fmt> command line option.</p></div> +in the --date-format=<fmt> command-line option.</p></div> <div class="dlist"><dl> <dt class="hdlist1"> <tt>raw</tt> @@ -1213,7 +1213,7 @@ <p> Marks the end of the stream. This command is optional unless the <tt>done</tt> feature was requested using the - <tt>--done</tt> command line option or <tt>feature done</tt> command. + <tt>--done</tt> command-line option or <tt>feature done</tt> command. </p> </dd> <dt class="hdlist1"> @@ -1317,7 +1317,7 @@ <tt><name></tt> and <tt><email></tt> are free-form and may contain any sequence of bytes, except <tt>LT</tt>, <tt>GT</tt> and <tt>LF</tt>. <tt><name></tt> is typically UTF-8 encoded.</p></div> <div class="paragraph"><p>The time of the change is specified by <tt><when></tt> using the date format -that was selected by the --date-format=<fmt> command line option. +that was selected by the --date-format=<fmt> command-line option. See “Date Formats” above for the set of supported formats, and their syntax.</p></div> </div> @@ -2055,7 +2055,7 @@ <div class="paragraph"><p>Option commands must be the first commands on the input (not counting feature commands), to give an option command after any non-option command is an error.</p></div> -<div class="paragraph"><p>The following commandline options change import semantics and may therefore +<div class="paragraph"><p>The following command-line options change import semantics and may therefore not be passed as option:</p></div> <div class="ulist"><ul> <li> @@ -2089,7 +2089,7 @@ <h3 id="_tt_done_tt"><tt>done</tt></h3> <div class="paragraph"><p>If the <tt>done</tt> feature is not in use, treated as if EOF was read. This can be used to tell fast-import to finish early.</p></div> -<div class="paragraph"><p>If the <tt>--done</tt> command line option or <tt>feature done</tt> command is +<div class="paragraph"><p>If the <tt>--done</tt> command-line option or <tt>feature done</tt> command is in use, the <tt>done</tt> command is mandatory and marks the end of the stream.</p></div> </div> @@ -2448,7 +2448,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2013-11-12 15:22:25 PST +Last updated 2014-06-06 12:15:38 PDT </div> </div> </body>
diff --git a/git-fast-import.txt b/git-fast-import.txt index fd22a9a..3ffa2fa 100644 --- a/git-fast-import.txt +++ b/git-fast-import.txt
@@ -231,7 +231,7 @@ ~~~~~~~~~~~~ The following date formats are supported. A frontend should select the format it will use for this import by passing the format name -in the \--date-format=<fmt> command line option. +in the \--date-format=<fmt> command-line option. `raw`:: This is the Git native format and is `<time> SP <offutc>`. @@ -348,7 +348,7 @@ `done`:: Marks the end of the stream. This command is optional unless the `done` feature was requested using the - `--done` command line option or `feature done` command. + `--done` command-line option or `feature done` command. `cat-blob`:: Causes fast-import to print a blob in 'cat-file --batch' @@ -437,7 +437,7 @@ of bytes, except `LT`, `GT` and `LF`. `<name>` is typically UTF-8 encoded. The time of the change is specified by `<when>` using the date format -that was selected by the \--date-format=<fmt> command line option. +that was selected by the \--date-format=<fmt> command-line option. See ``Date Formats'' above for the set of supported formats, and their syntax. @@ -1085,7 +1085,7 @@ feature commands), to give an option command after any non-option command is an error. -The following commandline options change import semantics and may therefore +The following command-line options change import semantics and may therefore not be passed as option: * date-format @@ -1099,7 +1099,7 @@ If the `done` feature is not in use, treated as if EOF was read. This can be used to tell fast-import to finish early. -If the `--done` command line option or `feature done` command is +If the `--done` command-line option or `feature done` command is in use, the `done` command is mandatory and marks the end of the stream.
diff --git a/git-help.html b/git-help.html index c802874..d398327 100644 --- a/git-help.html +++ b/git-help.html
@@ -857,9 +857,9 @@ <div class="sectionbody"> <div class="sect2"> <h3 id="_help_format">help.format</h3> -<div class="paragraph"><p>If no command line option is passed, the <em>help.format</em> configuration +<div class="paragraph"><p>If no command-line option is passed, the <em>help.format</em> configuration variable will be checked. The following values are supported for this -variable; they make <em>git help</em> behave as their corresponding command +variable; they make <em>git help</em> behave as their corresponding command- line option:</p></div> <div class="ulist"><ul> <li> @@ -882,14 +882,14 @@ <div class="sect2"> <h3 id="_help_browser_web_browser_and_browser_lt_tool_gt_path">help.browser, web.browser and browser.<tool>.path</h3> <div class="paragraph"><p>The <em>help.browser</em>, <em>web.browser</em> and <em>browser.<tool>.path</em> will also -be checked if the <em>web</em> format is chosen (either by command line +be checked if the <em>web</em> format is chosen (either by command-line option or configuration variable). See <em>-w|--web</em> in the OPTIONS section above and <a href="git-web--browse.html">git-web--browse(1)</a>.</p></div> </div> <div class="sect2"> <h3 id="_man_viewer">man.viewer</h3> -<div class="paragraph"><p>The <em>man.viewer</em> config variable will be checked if the <em>man</em> format -is chosen. The following values are currently supported:</p></div> +<div class="paragraph"><p>The <em>man.viewer</em> configuration variable will be checked if the <em>man</em> +format is chosen. The following values are currently supported:</p></div> <div class="ulist"><ul> <li> <p> @@ -921,7 +921,7 @@ viewer = konqueror viewer = woman</tt></pre> </div></div> -<div class="paragraph"><p>will try to use konqueror first. But this may fail (for example if +<div class="paragraph"><p>will try to use konqueror first. But this may fail (for example, if DISPLAY is not set) and in that case emacs' woman mode will be tried.</p></div> <div class="paragraph"><p>If everything fails, or if no viewer is configured, the viewer specified in the GIT_MAN_VIEWER environment variable will be tried. If that @@ -987,7 +987,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2013-08-20 08:40:27 PDT +Last updated 2014-06-06 12:15:38 PDT </div> </div> </body>
diff --git a/git-help.txt b/git-help.txt index b21e9d7..3956525 100644 --- a/git-help.txt +++ b/git-help.txt
@@ -80,9 +80,9 @@ help.format ~~~~~~~~~~~ -If no command line option is passed, the 'help.format' configuration +If no command-line option is passed, the 'help.format' configuration variable will be checked. The following values are supported for this -variable; they make 'git help' behave as their corresponding command +variable; they make 'git help' behave as their corresponding command- line option: * "man" corresponds to '-m|--man', @@ -93,15 +93,15 @@ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The 'help.browser', 'web.browser' and 'browser.<tool>.path' will also -be checked if the 'web' format is chosen (either by command line +be checked if the 'web' format is chosen (either by command-line option or configuration variable). See '-w|--web' in the OPTIONS section above and linkgit:git-web{litdd}browse[1]. man.viewer ~~~~~~~~~~ -The 'man.viewer' config variable will be checked if the 'man' format -is chosen. The following values are currently supported: +The 'man.viewer' configuration variable will be checked if the 'man' +format is chosen. The following values are currently supported: * "man": use the 'man' program as usual, * "woman": use 'emacsclient' to launch the "woman" mode in emacs @@ -124,7 +124,7 @@ viewer = woman ------------------------------------------------ -will try to use konqueror first. But this may fail (for example if +will try to use konqueror first. But this may fail (for example, if DISPLAY is not set) and in that case emacs' woman mode will be tried. If everything fails, or if no viewer is configured, the viewer specified diff --git a/git-ls-files.html b/git-ls-files.html index 6c13652..22be2c0 100644 --- a/git-ls-files.html +++ b/git-ls-files.html
@@ -1123,21 +1123,21 @@ <div class="olist arabic"><ol class="arabic"> <li> <p> -The command line flag --exclude=<pattern> specifies a +The command-line flag --exclude=<pattern> specifies a single pattern. Patterns are ordered in the same order they appear in the command line. </p> </li> <li> <p> -The command line flag --exclude-from=<file> specifies a +The command-line flag --exclude-from=<file> specifies a file containing a list of patterns. Patterns are ordered in the same order they appear in the file. </p> </li> <li> <p> -The command line flag --exclude-per-directory=<name> specifies +The command-line flag --exclude-per-directory=<name> specifies a name of the file in each directory <em>git ls-files</em> examines, normally <tt>.gitignore</tt>. Files in deeper directories take precedence. Patterns are ordered in the @@ -1168,7 +1168,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2013-08-20 08:40:27 PDT +Last updated 2014-06-06 12:15:38 PDT </div> </div> </body>
diff --git a/git-ls-files.txt b/git-ls-files.txt index c0856a6..e26f01f 100644 --- a/git-ls-files.txt +++ b/git-ls-files.txt
@@ -185,15 +185,15 @@ These exclude patterns come from these places, in order: - 1. The command line flag --exclude=<pattern> specifies a + 1. The command-line flag --exclude=<pattern> specifies a single pattern. Patterns are ordered in the same order they appear in the command line. - 2. The command line flag --exclude-from=<file> specifies a + 2. The command-line flag --exclude-from=<file> specifies a file containing a list of patterns. Patterns are ordered in the same order they appear in the file. - 3. The command line flag --exclude-per-directory=<name> specifies + 3. The command-line flag --exclude-per-directory=<name> specifies a name of the file in each directory 'git ls-files' examines, normally `.gitignore`. Files in deeper directories take precedence. Patterns are ordered in the
diff --git a/git-read-tree.html b/git-read-tree.html index 26409e4..2cf246b 100644 --- a/git-read-tree.html +++ b/git-read-tree.html
@@ -1129,7 +1129,7 @@ "merged"), the original tree (stage 1, aka "orig"), and the two trees you are trying to merge (stage 2 and 3 respectively).</p></div> <div class="paragraph"><p>The order of stages 1, 2 and 3 (hence the order of three -<tree-ish> command line arguments) are significant when you +<tree-ish> command-line arguments) are significant when you start a 3-way merge with an index file that is already populated. Here is an outline of how the algorithm works:</p></div> <div class="ulist"><ul> @@ -1294,7 +1294,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2014-04-08 12:47:26 PDT +Last updated 2014-06-06 12:15:38 PDT </div> </div> </body>
diff --git a/git-read-tree.txt b/git-read-tree.txt index 056c0db..fa1d557 100644 --- a/git-read-tree.txt +++ b/git-read-tree.txt
@@ -283,7 +283,7 @@ you are trying to merge (stage 2 and 3 respectively). The order of stages 1, 2 and 3 (hence the order of three -<tree-ish> command line arguments) are significant when you +<tree-ish> command-line arguments) are significant when you start a 3-way merge with an index file that is already populated. Here is an outline of how the algorithm works:
diff --git a/git-rev-parse.html b/git-rev-parse.html index 5f4aa22..bd5b4dc 100644 --- a/git-rev-parse.html +++ b/git-rev-parse.html
@@ -1364,7 +1364,9 @@ <p> The suffix <em>@{upstream}</em> to a branchname (short form <em><branchname>@{u}</em>) refers to the branch that the branch specified by branchname is set to build on - top of. A missing branchname defaults to the current one. + top of (configured with <tt>branch.<name>.remote</tt> and + <tt>branch.<name>.merge</tt>). A missing branchname defaults to the + current one. </p> </dd> <dt class="hdlist1"> diff --git a/git-send-email.html b/git-send-email.html index 9a14512..2febf3b 100644 --- a/git-send-email.html +++ b/git-send-email.html
@@ -763,7 +763,7 @@ files in the directory), or directly as a revision list. In the last case, any format accepted by <a href="git-format-patch.html">git-format-patch(1)</a> can be passed to git send-email.</p></div> -<div class="paragraph"><p>The header of the email is configurable by command line options. If not +<div class="paragraph"><p>The header of the email is configurable via command-line options. If not specified on the command line, the user will be prompted with a ReadLine enabled interface to provide the necessary information.</p></div> <div class="paragraph"><p>There are two formats accepted for patch files:</p></div> @@ -833,7 +833,7 @@ <div class="paragraph"><p>When <em>--compose</em> is used, git send-email will use the From, Subject, and In-Reply-To headers specified in the message. If the body of the message (what you type after the headers and a blank line) only contains blank -(or Git: prefixed) lines the summary won’t be sent, but From, Subject, +(or Git: prefixed) lines, the summary won’t be sent, but From, Subject, and In-Reply-To headers will be used unless they are removed.</p></div> <div class="paragraph"><p>Missing From or In-Reply-To headers will be prompted for.</p></div> <div class="paragraph"><p>See the CONFIGURATION section for <em>sendemail.multiedit</em>.</p></div> @@ -845,7 +845,7 @@ <p> Specify the sender of the emails. If not specified on the command line, the value of the <em>sendemail.from</em> configuration option is used. If - neither the command line option nor <em>sendemail.from</em> are set, then the + neither the command-line option nor <em>sendemail.from</em> are set, then the user will be prompted for the value. The default for the prompt will be the value of GIT_AUTHOR_IDENT, or GIT_COMMITTER_IDENT if that is not set, as returned by "git var -l". @@ -1410,7 +1410,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2013-08-20 08:40:27 PDT +Last updated 2014-06-06 12:15:38 PDT </div> </div> </body>
diff --git a/git-send-email.txt b/git-send-email.txt index f0e57a5..d0fa18a 100644 --- a/git-send-email.txt +++ b/git-send-email.txt
@@ -20,7 +20,7 @@ last case, any format accepted by linkgit:git-format-patch[1] can be passed to git send-email. -The header of the email is configurable by command line options. If not +The header of the email is configurable via command-line options. If not specified on the command line, the user will be prompted with a ReadLine enabled interface to provide the necessary information. @@ -68,7 +68,7 @@ When '--compose' is used, git send-email will use the From, Subject, and In-Reply-To headers specified in the message. If the body of the message (what you type after the headers and a blank line) only contains blank -(or Git: prefixed) lines the summary won't be sent, but From, Subject, +(or Git: prefixed) lines, the summary won't be sent, but From, Subject, and In-Reply-To headers will be used unless they are removed. + Missing From or In-Reply-To headers will be prompted for. @@ -78,7 +78,7 @@ --from=<address>:: Specify the sender of the emails. If not specified on the command line, the value of the 'sendemail.from' configuration option is used. If - neither the command line option nor 'sendemail.from' are set, then the + neither the command-line option nor 'sendemail.from' are set, then the user will be prompted for the value. The default for the prompt will be the value of GIT_AUTHOR_IDENT, or GIT_COMMITTER_IDENT if that is not set, as returned by "git var -l".
diff --git a/git-svn.html b/git-svn.html index a2f1c63..cbe29f0 100644 --- a/git-svn.html +++ b/git-svn.html
@@ -1003,8 +1003,8 @@ <pre class="content">config key: svn-remote.<name>.ignore-paths</pre> <div class="attribution"> </div></div> -<div class="paragraph"><p>If the ignore-paths config key is set and the command line option is -also given, both regular expressions will be used.</p></div> +<div class="paragraph"><p>If the ignore-paths configuration key is set, and the command-line +option is also given, both regular expressions will be used.</p></div> <div class="paragraph"><p>Examples:</p></div> <div class="openblock"> <div class="content"> @@ -2418,7 +2418,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2014-05-02 14:41:49 PDT +Last updated 2014-06-06 12:15:38 PDT </div> </div> </body>
diff --git a/git-svn.txt b/git-svn.txt index fce5853..44c970c 100644 --- a/git-svn.txt +++ b/git-svn.txt
@@ -148,8 +148,8 @@ [verse] config key: svn-remote.<name>.ignore-paths + -If the ignore-paths config key is set and the command line option is -also given, both regular expressions will be used. +If the ignore-paths configuration key is set, and the command-line +option is also given, both regular expressions will be used. + Examples: +
diff --git a/git-web--browse.html b/git-web--browse.html index bdd0a19..0f88c05 100644 --- a/git-web--browse.html +++ b/git-web--browse.html
@@ -900,7 +900,7 @@ <div class="sect2"> <h3 id="_conf_var_from_c_option_and_web_browser">CONF.VAR (from -c option) and web.browser</h3> <div class="paragraph"><p>The web browser can be specified using a configuration variable passed -with the -c (or --config) command line option, or the <em>web.browser</em> +with the -c (or --config) command-line option, or the <em>web.browser</em> configuration variable if the former is not used.</p></div> </div> <div class="sect2"> @@ -925,7 +925,7 @@ <div class="sect1"> <h2 id="_note_about_konqueror">Note about konqueror</h2> <div class="sectionbody"> -<div class="paragraph"><p>When <em>konqueror</em> is specified by a command line option or a +<div class="paragraph"><p>When <em>konqueror</em> is specified by a command-line option or a configuration variable, we launch <em>kfmclient</em> to try to open the HTML man page on an already opened konqueror in a new tab if possible.</p></div> <div class="paragraph"><p>For consistency, we also try such a trick if <em>browser.konqueror.path</em> is @@ -964,7 +964,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2013-11-01 09:52:04 PDT +Last updated 2014-06-06 12:15:38 PDT </div> </div> </body>
diff --git a/git-web--browse.txt b/git-web--browse.txt index 2de575f..16ede5b 100644 --- a/git-web--browse.txt +++ b/git-web--browse.txt
@@ -62,7 +62,7 @@ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The web browser can be specified using a configuration variable passed -with the -c (or --config) command line option, or the 'web.browser' +with the -c (or --config) command-line option, or the 'web.browser' configuration variable if the former is not used. browser.<tool>.path @@ -87,7 +87,7 @@ Note about konqueror -------------------- -When 'konqueror' is specified by a command line option or a +When 'konqueror' is specified by a command-line option or a configuration variable, we launch 'kfmclient' to try to open the HTML man page on an already opened konqueror in a new tab if possible.
diff --git a/git.html b/git.html index 3658d01..5d9c45c 100644 --- a/git.html +++ b/git.html
@@ -772,7 +772,7 @@ <div class="paragraph"><p>After you mastered the basic concepts, you can come back to this page to learn what commands Git offers. You can learn more about individual Git commands with "git help command". <a href="gitcli.html">gitcli(7)</a> -manual page gives you an overview of the command line command syntax.</p></div> +manual page gives you an overview of the command-line command syntax.</p></div> <div class="paragraph"><p>Formatted and hyperlinked version of the latest Git documentation can be viewed at <tt>http://git-htmldocs.googlecode.com/git/git.html</tt>.</p></div> </div> @@ -2399,7 +2399,7 @@ <dd> <p> Set the path to the root of the working tree. - This can also be controlled by the <em>--work-tree</em> command line + This can also be controlled by the <em>--work-tree</em> command-line option and the core.worktree configuration variable. </p> </dd> @@ -2626,7 +2626,7 @@ <p> If this environment variable is set, then Git commands which need to acquire passwords or passphrases (e.g. for HTTP or IMAP authentication) - will call this program with a suitable prompt as command line argument + will call this program with a suitable prompt as command-line argument and read the password from its STDOUT. See also the <em>core.askpass</em> option in <a href="git-config.html">git-config(1)</a>. </p> @@ -2866,7 +2866,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2014-05-09 11:55:44 PDT +Last updated 2014-06-06 12:15:38 PDT </div> </div> </body>
diff --git a/git.txt b/git.txt index b075e0b..3bd68b0 100644 --- a/git.txt +++ b/git.txt
@@ -29,7 +29,7 @@ After you mastered the basic concepts, you can come back to this page to learn what commands Git offers. You can learn more about individual Git commands with "git help command". linkgit:gitcli[7] -manual page gives you an overview of the command line command syntax. +manual page gives you an overview of the command-line command syntax. Formatted and hyperlinked version of the latest Git documentation can be viewed at `http://git-htmldocs.googlecode.com/git/git.html`. @@ -39,7 +39,7 @@ ============ You are reading the documentation for the latest (possibly -unreleased) version of Git, that is available from 'master' +unreleased) version of Git, that is available from the 'master' branch of the `git.git` repository. Documentation for older releases are available here: @@ -755,7 +755,7 @@ 'GIT_WORK_TREE':: Set the path to the root of the working tree. - This can also be controlled by the '--work-tree' command line + This can also be controlled by the '--work-tree' command-line option and the core.worktree configuration variable. 'GIT_NAMESPACE':: @@ -880,7 +880,7 @@ 'GIT_ASKPASS':: If this environment variable is set, then Git commands which need to acquire passwords or passphrases (e.g. for HTTP or IMAP authentication) - will call this program with a suitable prompt as command line argument + will call this program with a suitable prompt as command-line argument and read the password from its STDOUT. See also the 'core.askpass' option in linkgit:git-config[1].
diff --git a/gitcli.html b/gitcli.html index f1025ea..3ec9a17 100644 --- a/gitcli.html +++ b/gitcli.html
@@ -741,7 +741,7 @@ <h2>NAME</h2> <div class="sectionbody"> <p>gitcli - - Git command line interface and conventions + Git command-line interface and conventions </p> </div> </div> @@ -823,7 +823,7 @@ <div class="ulist"><ul> <li> <p> -it’s preferred to use the non dashed form of Git commands, which means that +it’s preferred to use the non-dashed form of Git commands, which means that you should prefer <tt>git foo</tt> to <tt>git-foo</tt>. </p> </li> @@ -835,7 +835,7 @@ </li> <li> <p> -when a command line option takes an argument, use the <em>stuck</em> form. In +when a command-line option takes an argument, use the <em>stuck</em> form. In other words, write <tt>git foo -oArg</tt> instead of <tt>git foo -o Arg</tt> for short options, and <tt>git foo --long-opt=Arg</tt> instead of <tt>git foo --long-opt Arg</tt> for long options. An option that takes optional option-argument must be @@ -873,7 +873,7 @@ <div class="sect2"> <h3 id="_magic_options">Magic Options</h3> <div class="paragraph"><p>Commands which have the enhanced option parser activated all understand a -couple of magic command line options:</p></div> +couple of magic command-line options:</p></div> <div class="dlist"><dl> <dt class="hdlist1"> -h @@ -1005,7 +1005,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2014-02-07 12:30:09 PST +Last updated 2014-06-06 12:15:38 PDT </div> </div> </body>
diff --git a/gitcli.txt b/gitcli.txt index 1c3e109..dfe7d83 100644 --- a/gitcli.txt +++ b/gitcli.txt
@@ -3,7 +3,7 @@ NAME ---- -gitcli - Git command line interface and conventions +gitcli - Git command-line interface and conventions SYNOPSIS -------- @@ -66,13 +66,13 @@ Here are the rules regarding the "flags" that you should follow when you are scripting Git: - * it's preferred to use the non dashed form of Git commands, which means that + * it's preferred to use the non-dashed form of Git commands, which means that you should prefer `git foo` to `git-foo`. * splitting short options to separate words (prefer `git foo -a -b` to `git foo -ab`, the latter may not even work). - * when a command line option takes an argument, use the 'stuck' form. In + * when a command-line option takes an argument, use the 'stuck' form. In other words, write `git foo -oArg` instead of `git foo -o Arg` for short options, and `git foo --long-opt=Arg` instead of `git foo --long-opt Arg` for long options. An option that takes optional option-argument must be @@ -103,7 +103,7 @@ Magic Options ~~~~~~~~~~~~~ Commands which have the enhanced option parser activated all understand a -couple of magic command line options: +couple of magic command-line options: -h:: gives a pretty printed usage of the command.
diff --git a/gitk.html b/gitk.html index 8a4a8eb..00a743f 100644 --- a/gitk.html +++ b/gitk.html
@@ -773,7 +773,7 @@ gitk-specific options.</p></div> <div class="paragraph"><p>gitk generally only understands options with arguments in the <em>sticked</em> form (see <a href="gitcli.html">gitcli(7)</a>) due to limitations in the -command line parser.</p></div> +command-line parser.</p></div> <div class="sect2"> <h3 id="_rev_list_options_and_arguments">rev-list options and arguments</h3> <div class="paragraph"><p>This manual page describes only the most frequently used options. See @@ -1099,7 +1099,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2014-03-28 15:14:58 PDT +Last updated 2014-06-06 12:15:38 PDT </div> </div> </body>
diff --git a/gitk.txt b/gitk.txt index 7e03fcc..7ae50aa 100644 --- a/gitk.txt +++ b/gitk.txt
@@ -27,7 +27,7 @@ gitk generally only understands options with arguments in the 'sticked' form (see linkgit:gitcli[7]) due to limitations in the -command line parser. +command-line parser. rev-list options and arguments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/gitrevisions.html b/gitrevisions.html index 20f806c..c72ddcc 100644 --- a/gitrevisions.html +++ b/gitrevisions.html
@@ -923,7 +923,9 @@ <p> The suffix <em>@{upstream}</em> to a branchname (short form <em><branchname>@{u}</em>) refers to the branch that the branch specified by branchname is set to build on - top of. A missing branchname defaults to the current one. + top of (configured with <tt>branch.<name>.remote</tt> and + <tt>branch.<name>.merge</tt>). A missing branchname defaults to the + current one. </p> </dd> <dt class="hdlist1"> diff --git a/gitweb.conf.html b/gitweb.conf.html index a502e0a..ad204e3 100644 --- a/gitweb.conf.html +++ b/gitweb.conf.html
@@ -1892,7 +1892,7 @@ $feature{'snapshot'}{'override'} = 1;</tt></pre> </div></div> <div class="paragraph"><p>If you allow overriding for the snapshot feature, you can specify which -snapshot formats are globally disabled. You can also add any command line +snapshot formats are globally disabled. You can also add any command-line options you want (such as setting the compression level). For instance, you can disable Zip compressed snapshots and set <strong>gzip</strong>(1) to run at level 6 by adding the following lines to your gitweb configuration file:</p></div> @@ -1998,7 +1998,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2014-02-07 12:30:09 PST +Last updated 2014-06-06 12:15:38 PDT </div> </div> </body> diff --git a/gitweb.conf.txt b/gitweb.conf.txt index 952f503..ebe7a6c 100644 --- a/gitweb.conf.txt +++ b/gitweb.conf.txt
@@ -904,7 +904,7 @@ $feature{'snapshot'}{'override'} = 1; If you allow overriding for the snapshot feature, you can specify which -snapshot formats are globally disabled. You can also add any command line +snapshot formats are globally disabled. You can also add any command-line options you want (such as setting the compression level). For instance, you can disable Zip compressed snapshots and set *gzip*(1) to run at level 6 by adding the following lines to your gitweb configuration file: diff --git a/howto-index.html b/howto-index.html index f81fbbb..29aa145 100644 --- a/howto-index.html +++ b/howto-index.html
@@ -745,6 +745,15 @@ <div class="ulist"><ul> <li> <p> +<a href="howto/keep-canonical-history-correct.html">keep-canonical-history-correct</a> by Junio C Hamano <<a href="mailto:gitster@pobox.com">gitster@pobox.com</a>> +</p> +</li> +</ul></div> +<div class="paragraph"><p>This how-to explains a method for keeping a +project’s history correct when using git pull.</p></div> +<div class="ulist"><ul> +<li> +<p> <a href="howto/maintain-git.html">maintain-git</a> by Junio C Hamano <<a href="mailto:gitster@pobox.com">gitster@pobox.com</a>> </p> </li> @@ -876,7 +885,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2014-05-20 16:23:10 PDT +Last updated 2014-06-06 12:15:39 PDT </div> </div> </body>
diff --git a/howto-index.txt b/howto-index.txt index 5bfce12..8f2edca 100644 --- a/howto-index.txt +++ b/howto-index.txt
@@ -4,6 +4,12 @@ Here is a collection of mailing list postings made by various people describing how they use Git in their workflow. +* link:howto/keep-canonical-history-correct.html[keep-canonical-history-correct] by Junio C Hamano <gitster@pobox.com> + +This how-to explains a method for keeping a +project's history correct when using git pull. + + * link:howto/maintain-git.html[maintain-git] by Junio C Hamano <gitster@pobox.com> Imagine that Git development is racing along as usual, when our friendly
diff --git a/howto/keep-canonical-history-correct.html b/howto/keep-canonical-history-correct.html new file mode 100644 index 0000000..91a2868 --- /dev/null +++ b/howto/keep-canonical-history-correct.html
@@ -0,0 +1,945 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" + "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"> +<head> +<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" /> +<meta name="generator" content="AsciiDoc 8.6.6" /> +<title>Keep authoritative canonical history correct with git pull</title> +<style type="text/css"> +/* Shared CSS for AsciiDoc xhtml11 and html5 backends */ + +/* Default font. */ +body { + font-family: Georgia,serif; +} + +/* Title font. */ +h1, h2, h3, h4, h5, h6, +div.title, caption.title, +thead, p.table.header, +#toctitle, +#author, #revnumber, #revdate, #revremark, +#footer { + font-family: Arial,Helvetica,sans-serif; +} + +body { + margin: 1em 5% 1em 5%; +} + +a { + color: blue; + text-decoration: underline; +} +a:visited { + color: fuchsia; +} + +em { + font-style: italic; + color: navy; +} + +strong { + font-weight: bold; + color: #083194; +} + +h1, h2, h3, h4, h5, h6 { + color: #527bbd; + margin-top: 1.2em; + margin-bottom: 0.5em; + line-height: 1.3; +} + +h1, h2, h3 { + border-bottom: 2px solid silver; +} +h2 { + padding-top: 0.5em; +} +h3 { + float: left; +} +h3 + * { + clear: left; +} +h5 { + font-size: 1.0em; +} + +div.sectionbody { + margin-left: 0; +} + +hr { + border: 1px solid silver; +} + +p { + margin-top: 0.5em; + margin-bottom: 0.5em; +} + +ul, ol, li > p { + margin-top: 0; +} +ul > li { color: #aaa; } +ul > li > * { color: black; } + +pre { + padding: 0; + margin: 0; +} + +#author { + color: #527bbd; + font-weight: bold; + font-size: 1.1em; +} +#email { +} +#revnumber, #revdate, #revremark { +} + +#footer { + font-size: small; + border-top: 2px solid silver; + padding-top: 0.5em; + margin-top: 4.0em; +} +#footer-text { + float: left; + padding-bottom: 0.5em; +} +#footer-badges { + float: right; + padding-bottom: 0.5em; +} + +#preamble { + margin-top: 1.5em; + margin-bottom: 1.5em; +} +div.imageblock, div.exampleblock, div.verseblock, +div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock, +div.admonitionblock { + margin-top: 1.0em; + margin-bottom: 1.5em; +} +div.admonitionblock { + margin-top: 2.0em; + margin-bottom: 2.0em; + margin-right: 10%; + color: #606060; +} + +div.content { /* Block element content. */ + padding: 0; +} + +/* Block element titles. */ +div.title, caption.title { + color: #527bbd; + font-weight: bold; + text-align: left; + margin-top: 1.0em; + margin-bottom: 0.5em; +} +div.title + * { + margin-top: 0; +} + +td div.title:first-child { + margin-top: 0.0em; +} +div.content div.title:first-child { + margin-top: 0.0em; +} +div.content + div.title { + margin-top: 0.0em; +} + +div.sidebarblock > div.content { + background: #ffffee; + border: 1px solid #dddddd; + border-left: 4px solid #f0f0f0; + padding: 0.5em; +} + +div.listingblock > div.content { + border: 1px solid #dddddd; + border-left: 5px solid #f0f0f0; + background: #f8f8f8; + padding: 0.5em; +} + +div.quoteblock, div.verseblock { + padding-left: 1.0em; + margin-left: 1.0em; + margin-right: 10%; + border-left: 5px solid #f0f0f0; + color: #888; +} + +div.quoteblock > div.attribution { + padding-top: 0.5em; + text-align: right; +} + +div.verseblock > pre.content { + font-family: inherit; + font-size: inherit; +} +div.verseblock > div.attribution { + padding-top: 0.75em; + text-align: left; +} +/* DEPRECATED: Pre version 8.2.7 verse style literal block. */ +div.verseblock + div.attribution { + text-align: left; +} + +div.admonitionblock .icon { + vertical-align: top; + font-size: 1.1em; + font-weight: bold; + text-decoration: underline; + color: #527bbd; + padding-right: 0.5em; +} +div.admonitionblock td.content { + padding-left: 0.5em; + border-left: 3px solid #dddddd; +} + +div.exampleblock > div.content { + border-left: 3px solid #dddddd; + padding-left: 0.5em; +} + +div.imageblock div.content { padding-left: 0; } +span.image img { border-style: none; } +a.image:visited { color: white; } + +dl { + margin-top: 0.8em; + margin-bottom: 0.8em; +} +dt { + margin-top: 0.5em; + margin-bottom: 0; + font-style: normal; + color: navy; +} +dd > *:first-child { + margin-top: 0.1em; +} + +ul, ol { + list-style-position: outside; +} +ol.arabic { + list-style-type: decimal; +} +ol.loweralpha { + list-style-type: lower-alpha; +} +ol.upperalpha { + list-style-type: upper-alpha; +} +ol.lowerroman { + list-style-type: lower-roman; +} +ol.upperroman { + list-style-type: upper-roman; +} + +div.compact ul, div.compact ol, +div.compact p, div.compact p, +div.compact div, div.compact div { + margin-top: 0.1em; + margin-bottom: 0.1em; +} + +tfoot { + font-weight: bold; +} +td > div.verse { + white-space: pre; +} + +div.hdlist { + margin-top: 0.8em; + margin-bottom: 0.8em; +} +div.hdlist tr { + padding-bottom: 15px; +} +dt.hdlist1.strong, td.hdlist1.strong { + font-weight: bold; +} +td.hdlist1 { + vertical-align: top; + font-style: normal; + padding-right: 0.8em; + color: navy; +} +td.hdlist2 { + vertical-align: top; +} +div.hdlist.compact tr { + margin: 0; + padding-bottom: 0; +} + +.comment { + background: yellow; +} + +.footnote, .footnoteref { + font-size: 0.8em; +} + +span.footnote, span.footnoteref { + vertical-align: super; +} + +#footnotes { + margin: 20px 0 20px 0; + padding: 7px 0 0 0; +} + +#footnotes div.footnote { + margin: 0 0 5px 0; +} + +#footnotes hr { + border: none; + border-top: 1px solid silver; + height: 1px; + text-align: left; + margin-left: 0; + width: 20%; + min-width: 100px; +} + +div.colist td { + padding-right: 0.5em; + padding-bottom: 0.3em; + vertical-align: top; +} +div.colist td img { + margin-top: 0.3em; +} + +@media print { + #footer-badges { display: none; } +} + +#toc { + margin-bottom: 2.5em; +} + +#toctitle { + color: #527bbd; + font-size: 1.1em; + font-weight: bold; + margin-top: 1.0em; + margin-bottom: 0.1em; +} + +div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 { + margin-top: 0; + margin-bottom: 0; +} +div.toclevel2 { + margin-left: 2em; + font-size: 0.9em; +} +div.toclevel3 { + margin-left: 4em; + font-size: 0.9em; +} +div.toclevel4 { + margin-left: 6em; + font-size: 0.9em; +} + +span.aqua { color: aqua; } +span.black { color: black; } +span.blue { color: blue; } +span.fuchsia { color: fuchsia; } +span.gray { color: gray; } +span.green { color: green; } +span.lime { color: lime; } +span.maroon { color: maroon; } +span.navy { color: navy; } +span.olive { color: olive; } +span.purple { color: purple; } +span.red { color: red; } +span.silver { color: silver; } +span.teal { color: teal; } +span.white { color: white; } +span.yellow { color: yellow; } + +span.aqua-background { background: aqua; } +span.black-background { background: black; } +span.blue-background { background: blue; } +span.fuchsia-background { background: fuchsia; } +span.gray-background { background: gray; } +span.green-background { background: green; } +span.lime-background { background: lime; } +span.maroon-background { background: maroon; } +span.navy-background { background: navy; } +span.olive-background { background: olive; } +span.purple-background { background: purple; } +span.red-background { background: red; } +span.silver-background { background: silver; } +span.teal-background { background: teal; } +span.white-background { background: white; } +span.yellow-background { background: yellow; } + +span.big { font-size: 2em; } +span.small { font-size: 0.6em; } + +span.underline { text-decoration: underline; } +span.overline { text-decoration: overline; } +span.line-through { text-decoration: line-through; } + + +/* + * xhtml11 specific + * + * */ + +tt { + font-family: monospace; + font-size: inherit; + color: navy; +} + +div.tableblock { + margin-top: 1.0em; + margin-bottom: 1.5em; +} +div.tableblock > table { + border: 3px solid #527bbd; +} +thead, p.table.header { + font-weight: bold; + color: #527bbd; +} +p.table { + margin-top: 0; +} +/* Because the table frame attribute is overriden by CSS in most browsers. */ +div.tableblock > table[frame="void"] { + border-style: none; +} +div.tableblock > table[frame="hsides"] { + border-left-style: none; + border-right-style: none; +} +div.tableblock > table[frame="vsides"] { + border-top-style: none; + border-bottom-style: none; +} + + +/* + * html5 specific + * + * */ + +.monospaced { + font-family: monospace; + font-size: inherit; + color: navy; +} + +table.tableblock { + margin-top: 1.0em; + margin-bottom: 1.5em; +} +thead, p.tableblock.header { + font-weight: bold; + color: #527bbd; +} +p.tableblock { + margin-top: 0; +} +table.tableblock { + border-width: 3px; + border-spacing: 0px; + border-style: solid; + border-color: #527bbd; + border-collapse: collapse; +} +th.tableblock, td.tableblock { + border-width: 1px; + padding: 4px; + border-style: solid; + border-color: #527bbd; +} + +table.tableblock.frame-topbot { + border-left-style: hidden; + border-right-style: hidden; +} +table.tableblock.frame-sides { + border-top-style: hidden; + border-bottom-style: hidden; +} +table.tableblock.frame-none { + border-style: hidden; +} + +th.tableblock.halign-left, td.tableblock.halign-left { + text-align: left; +} +th.tableblock.halign-center, td.tableblock.halign-center { + text-align: center; +} +th.tableblock.halign-right, td.tableblock.halign-right { + text-align: right; +} + +th.tableblock.valign-top, td.tableblock.valign-top { + vertical-align: top; +} +th.tableblock.valign-middle, td.tableblock.valign-middle { + vertical-align: middle; +} +th.tableblock.valign-bottom, td.tableblock.valign-bottom { + vertical-align: bottom; +} + + +/* + * manpage specific + * + * */ + +body.manpage h1 { + padding-top: 0.5em; + padding-bottom: 0.5em; + border-top: 2px solid silver; + border-bottom: 2px solid silver; +} +body.manpage h2 { + border-style: none; +} +body.manpage div.sectionbody { + margin-left: 3em; +} + +@media print { + body.manpage div#toc { display: none; } +} +</style> +<script type="text/javascript"> +/*<+'])'); + // Function that scans the DOM tree for header elements (the DOM2 + // nodeIterator API would be a better technique but not supported by all + // browsers). + var iterate = function (el) { + for (var i = el.firstChild; i != null; i = i.nextSibling) { + if (i.nodeType == 1 /* Node.ELEMENT_NODE */) { + var mo = re.exec(i.tagName); + if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") { + result[result.length] = new TocEntry(i, getText(i), mo[1]-1); + } + iterate(i); + } + } + } + iterate(el); + return result; + } + + var toc = document.getElementById("toc"); + if (!toc) { + return; + } + + // Delete existing TOC entries in case we're reloading the TOC. + var tocEntriesToRemove = []; + var i; + for (i = 0; i < toc.childNodes.length; i++) { + var entry = toc.childNodes[i]; + if (entry.nodeName == 'div' + && entry.getAttribute("class") + && entry.getAttribute("class").match(/^toclevel/)) + tocEntriesToRemove.push(entry); + } + for (i = 0; i < tocEntriesToRemove.length; i++) { + toc.removeChild(tocEntriesToRemove[i]); + } + + // Rebuild TOC entries. + var entries = tocEntries(document.getElementById("content"), toclevels); + for (var i = 0; i < entries.length; ++i) { + var entry = entries[i]; + if (entry.element.id == "") + entry.element.id = "_toc_" + i; + var a = document.createElement("a"); + a.href = "#" + entry.element.id; + a.appendChild(document.createTextNode(entry.text)); + var div = document.createElement("div"); + div.appendChild(a); + div.className = "toclevel" + entry.toclevel; + toc.appendChild(div); + } + if (entries.length == 0) + toc.parentNode.removeChild(toc); +}, + + +///////////////////////////////////////////////////////////////////// +// Footnotes generator +///////////////////////////////////////////////////////////////////// + +/* Based on footnote generation code from: + * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html + */ + +footnotes: function () { + // Delete existing footnote entries in case we're reloading the footnodes. + var i; + var noteholder = document.getElementById("footnotes"); + if (!noteholder) { + return; + } + var entriesToRemove = []; + for (i = 0; i < noteholder.childNodes.length; i++) { + var entry = noteholder.childNodes[i]; + if (entry.nodeName == 'div' && entry.getAttribute("class") == "footnote") + entriesToRemove.push(entry); + } + for (i = 0; i < entriesToRemove.length; i++) { + noteholder.removeChild(entriesToRemove[i]); + } + + // Rebuild footnote entries. + var cont = document.getElementById("content"); + var spans = cont.getElementsByTagName("span"); + var refs = {}; + var n = 0; + for (i=0; i<spans.length; i++) { + if (spans[i].className == "footnote") { + n++; + var note = spans[i].getAttribute("data-note"); + if (!note) { + // Use [\s\S] in place of . so multi-line matches work. + // Because JavaScript has no s (dotall) regex flag. + note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1]; + spans[i].innerHTML = + "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n + + "' title='View footnote' class='footnote'>" + n + "</a>]"; + spans[i].setAttribute("data-note", note); + } + noteholder.innerHTML += + "<div class='footnote' id='_footnote_" + n + "'>" + + "<a href='#_footnoteref_" + n + "' title='Return to text'>" + + n + "</a>. " + note + "</div>"; + var id =spans[i].getAttribute("id"); + if (id != null) refs["#"+id] = n; + } + } + if (n == 0) + noteholder.parentNode.removeChild(noteholder); + else { + // Process footnoterefs. + for (i=0; i<spans.length; i++) { + if (spans[i].className == "footnoteref") { + var href = spans[i].getElementsByTagName("a")[0].getAttribute("href"); + href = href.match(/#.*/)[0]; // Because IE return full URL. + n = refs[href]; + spans[i].innerHTML = + "[<a href='#_footnote_" + n + + "' title='View footnote' class='footnote'>" + n + "</a>]"; + } + } + } +}, + +install: function(toclevels) { + var timerId; + + function reinstall() { + asciidoc.footnotes(); + if (toclevels) { + asciidoc.toc(toclevels); + } + } + + function reinstallAndRemoveTimer() { + clearInterval(timerId); + reinstall(); + } + + timerId = setInterval(reinstall, 500); + if (document.addEventListener) + document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false); + else + window.onload = reinstallAndRemoveTimer; +} + +} +asciidoc.install(); +/*]]>*/ +</script> +</head> +<body class="article"> +<div id="header"> +<h1>Keep authoritative canonical history correct with git pull</h1> +</div> +<div id="content"> +<div id="preamble"> +<div class="sectionbody"> +<div class="paragraph"><p>Sometimes a new project integrator will end up with project history +that appears to be "backwards" from what other project developers +expect. This howto presents a suggested integration workflow for +maintaining a central repository.</p></div> +<div class="paragraph"><p>Suppose that that central repository has this history:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt> ---o---o---A</tt></pre> +</div></div> +<div class="paragraph"><p>which ends at commit <tt>A</tt> (time flows from left to right and each node +in the graph is a commit, lines between them indicating parent-child +relationship).</p></div> +<div class="paragraph"><p>Then you clone it and work on your own commits, which leads you to +have this history in <strong>your</strong> repository:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt> ---o---o---A---B---C</tt></pre> +</div></div> +<div class="paragraph"><p>Imagine your coworker did the same and built on top of <tt>A</tt> in <strong>his</strong> +repository in the meantime, and then pushed it to the +central repository:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt> ---o---o---A---X---Y---Z</tt></pre> +</div></div> +<div class="paragraph"><p>Now, if you <tt>git push</tt> at this point, because your history that leads +to <tt>C</tt> lacks <tt>X</tt>, <tt>Y</tt> and <tt>Z</tt>, it will fail. You need to somehow make +the tip of your history a descendant of <tt>Z</tt>.</p></div> +<div class="paragraph"><p>One suggested way to solve the problem is "fetch and then merge", aka +<tt>git pull</tt>. When you fetch, your repository will have a history like +this:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt> ---o---o---A---B---C + \ + X---Y---Z</tt></pre> +</div></div> +<div class="paragraph"><p>Once you run merge after that, while still on <strong>your</strong> branch, i.e. <tt>C</tt>, +you will create a merge <tt>M</tt> and make the history look like this:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt> ---o---o---A---B---C---M + \ / + X---Y---Z</tt></pre> +</div></div> +<div class="paragraph"><p><tt>M</tt> is a descendant of <tt>Z</tt>, so you can push to update the central +repository. Such a merge <tt>M</tt> does not lose any commit in both +histories, so in that sense it may not be wrong, but when people want +to talk about "the authoritative canonical history that is shared +among the project participants", i.e. "the trunk", they often view +it as "commits you see by following the first-parent chain", and use +this command to view it:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt> $ git log --first-parent</tt></pre> +</div></div> +<div class="paragraph"><p>For all other people who observed the central repository after your +coworker pushed <tt>Z</tt> but before you pushed <tt>M</tt>, the commit on the trunk +used to be <tt>o-o-A-X-Y-Z</tt>. But because you made <tt>M</tt> while you were on +<tt>C</tt>, <tt>M</tt>'s first parent is <tt>C</tt>, so by pushing <tt>M</tt> to advance the +central repository, you made <tt>X-Y-Z</tt> a side branch, not on the trunk.</p></div> +<div class="paragraph"><p>You would rather want to have a history of this shape:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt> ---o---o---A---X---Y---Z---M' + \ / + B-----------C</tt></pre> +</div></div> +<div class="paragraph"><p>so that in the first-parent chain, it is clear that the project first +did <tt>X</tt> and then <tt>Y</tt> and then <tt>Z</tt> and merged a change that consists of +two commits <tt>B</tt> and <tt>C</tt> that achieves a single goal. You may have +worked on fixing the bug #12345 with these two patches, and the merge +<tt>M'</tt> with swapped parents can say in its log message "Merge +fix-bug-12345". Having a way to tell <tt>git pull</tt> to create a merge +but record the parents in reverse order may be a way to do so.</p></div> +<div class="paragraph"><p>Note that I said "achieves a single goal" above, because this is +important. "Swapping the merge order" only covers a special case +where the project does not care too much about having unrelated +things done on a single merge but cares a lot about first-parent +chain.</p></div> +<div class="paragraph"><p>There are multiple schools of thought about the "trunk" management.</p></div> +<div class="olist arabic"><ol class="arabic"> +<li> +<p> +Some projects want to keep a completely linear history without any + merges. Obviously, swapping the merge order would not match their + taste. You would need to flatten your history on top of the + updated upstream to result in a history of this shape instead: +</p> +<div class="listingblock"> +<div class="content"> +<pre><tt> ---o---o---A---X---Y---Z---B---C</tt></pre> +</div></div> +<div class="paragraph"><p>with <tt>git pull --rebase</tt> or something.</p></div> +</li> +<li> +<p> +Some projects tolerate merges in their history, but do not worry + too much about the first-parent order, and allow fast-forward + merges. To them, swapping the merge order does not hurt, but + it is unnecessary. +</p> +</li> +<li> +<p> +Some projects want each commit on the "trunk" to do one single + thing. The output of <tt>git log --first-parent</tt> in such a project + would show either a merge of a side branch that completes a single + theme, or a single commit that completes a single theme by itself. + If your two commits <tt>B</tt> and <tt>C</tt> (or they may even be two groups of + commits) were solving two independent issues, then the merge <tt>M'</tt> + we made in the earlier example by swapping the merge order is + still not up to the project standard. It merges two unrelated + efforts <tt>B</tt> and <tt>C</tt> at the same time. +</p> +</li> +</ol></div> +<div class="paragraph"><p>For projects in the last category (Git itself is one of them), +individual developers would want to prepare a history more like +this:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt> C0--C1--C2 topic-c + / + ---o---o---A master + \ + B0--B1--B2 topic-b</tt></pre> +</div></div> +<div class="paragraph"><p>That is, keeping separate topics on separate branches, perhaps like +so:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt> $ git clone $URL work && cd work + $ git checkout -b topic-b master + $ ... work to create B0, B1 and B2 to complete one theme + $ git checkout -b topic-c master + $ ... same for the theme of topic-c</tt></pre> +</div></div> +<div class="paragraph"><p>And then</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt> $ git checkout master + $ git pull --ff-only</tt></pre> +</div></div> +<div class="paragraph"><p>would grab <tt>X</tt>, <tt>Y</tt> and <tt>Z</tt> from the upstream and advance your master +branch:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt> C0--C1--C2 topic-c + / + ---o---o---A---X---Y---Z master + \ + B0--B1--B2 topic-b</tt></pre> +</div></div> +<div class="paragraph"><p>And then you would merge these two branches separately:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt> $ git merge topic-b + $ git merge topic-c</tt></pre> +</div></div> +<div class="paragraph"><p>to result in</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt> C0--C1---------C2 + / \ + ---o---o---A---X---Y---Z---M---N + \ / + B0--B1-----B2</tt></pre> +</div></div> +<div class="paragraph"><p>and push it back to the central repository.</p></div> +<div class="paragraph"><p>It is very much possible that while you are merging topic-b and +topic-c, somebody again advanced the history in the central repository +to put <tt>W</tt> on top of <tt>Z</tt>, and make your <tt>git push</tt> fail.</p></div> +<div class="paragraph"><p>In such a case, you would rewind to discard <tt>M</tt> and <tt>N</tt>, update the +tip of your <em>master</em> again and redo the two merges:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt> $ git reset --hard origin/master + $ git pull --ff-only + $ git merge topic-b + $ git merge topic-c</tt></pre> +</div></div> +<div class="paragraph"><p>The procedure will result in a history that looks like this:</p></div> +<div class="listingblock"> +<div class="content"> +<pre><tt> C0--C1--------------C2 + / \ + ---o---o---A---X---Y---Z---W---M'--N' + \ / + B0--B1---------B2</tt></pre> +</div></div> +<div class="paragraph"><p>See also <a href="http://git-blame.blogspot.com/2013/09/fun-with-first-parent-history.html">http://git-blame.blogspot.com/2013/09/fun-with-first-parent-history.html</a></p></div> +</div> +</div> +</div> +<div id="footnotes"><hr /></div> +<div id="footer"> +<div id="footer-text"> +Last updated 2014-06-06 12:15:48 PDT +</div> +</div> +</body> +</html> diff --git a/howto/keep-canonical-history-correct.txt b/howto/keep-canonical-history-correct.txt new file mode 100644 index 0000000..35d48ef --- /dev/null +++ b/howto/keep-canonical-history-correct.txt
@@ -0,0 +1,216 @@ +From: Junio C Hamano <gitster@pobox.com> +Date: Wed, 07 May 2014 13:15:39 -0700 +Subject: Beginner question on "Pull is mostly evil" +Abstract: This how-to explains a method for keeping a + project's history correct when using git pull. +Content-type: text/asciidoc + +Keep authoritative canonical history correct with git pull +========================================================== + +Sometimes a new project integrator will end up with project history +that appears to be "backwards" from what other project developers +expect. This howto presents a suggested integration workflow for +maintaining a central repository. + +Suppose that that central repository has this history: + +------------ + ---o---o---A +------------ + +which ends at commit `A` (time flows from left to right and each node +in the graph is a commit, lines between them indicating parent-child +relationship). + +Then you clone it and work on your own commits, which leads you to +have this history in *your* repository: + +------------ + ---o---o---A---B---C +------------ + +Imagine your coworker did the same and built on top of `A` in *his* +repository in the meantime, and then pushed it to the +central repository: + +------------ + ---o---o---A---X---Y---Z +------------ + +Now, if you `git push` at this point, because your history that leads +to `C` lacks `X`, `Y` and `Z`, it will fail. You need to somehow make +the tip of your history a descendant of `Z`. + +One suggested way to solve the problem is "fetch and then merge", aka +`git pull`. When you fetch, your repository will have a history like +this: + +------------ + ---o---o---A---B---C + \ + X---Y---Z +------------ + +Once you run merge after that, while still on *your* branch, i.e. `C`, +you will create a merge `M` and make the history look like this: + +------------ + ---o---o---A---B---C---M + \ / + X---Y---Z +------------ + +`M` is a descendant of `Z`, so you can push to update the central +repository. Such a merge `M` does not lose any commit in both +histories, so in that sense it may not be wrong, but when people want +to talk about "the authoritative canonical history that is shared +among the project participants", i.e. "the trunk", they often view +it as "commits you see by following the first-parent chain", and use +this command to view it: + +------------ + $ git log --first-parent +------------ + +For all other people who observed the central repository after your +coworker pushed `Z` but before you pushed `M`, the commit on the trunk +used to be `o-o-A-X-Y-Z`. But because you made `M` while you were on +`C`, `M`'s first parent is `C`, so by pushing `M` to advance the +central repository, you made `X-Y-Z` a side branch, not on the trunk. + +You would rather want to have a history of this shape: + +------------ + ---o---o---A---X---Y---Z---M' + \ / + B-----------C +------------ + +so that in the first-parent chain, it is clear that the project first +did `X` and then `Y` and then `Z` and merged a change that consists of +two commits `B` and `C` that achieves a single goal. You may have +worked on fixing the bug #12345 with these two patches, and the merge +`M'` with swapped parents can say in its log message "Merge +fix-bug-12345". Having a way to tell `git pull` to create a merge +but record the parents in reverse order may be a way to do so. + +Note that I said "achieves a single goal" above, because this is +important. "Swapping the merge order" only covers a special case +where the project does not care too much about having unrelated +things done on a single merge but cares a lot about first-parent +chain. + +There are multiple schools of thought about the "trunk" management. + + 1. Some projects want to keep a completely linear history without any + merges. Obviously, swapping the merge order would not match their + taste. You would need to flatten your history on top of the + updated upstream to result in a history of this shape instead: ++ +------------ + ---o---o---A---X---Y---Z---B---C +------------ ++ +with `git pull --rebase` or something. + + 2. Some projects tolerate merges in their history, but do not worry + too much about the first-parent order, and allow fast-forward + merges. To them, swapping the merge order does not hurt, but + it is unnecessary. + + 3. Some projects want each commit on the "trunk" to do one single + thing. The output of `git log --first-parent` in such a project + would show either a merge of a side branch that completes a single + theme, or a single commit that completes a single theme by itself. + If your two commits `B` and `C` (or they may even be two groups of + commits) were solving two independent issues, then the merge `M'` + we made in the earlier example by swapping the merge order is + still not up to the project standard. It merges two unrelated + efforts `B` and `C` at the same time. + +For projects in the last category (Git itself is one of them), +individual developers would want to prepare a history more like +this: + +------------ + C0--C1--C2 topic-c + / + ---o---o---A master + \ + B0--B1--B2 topic-b +------------ + +That is, keeping separate topics on separate branches, perhaps like +so: + +------------ + $ git clone $URL work && cd work + $ git checkout -b topic-b master + $ ... work to create B0, B1 and B2 to complete one theme + $ git checkout -b topic-c master + $ ... same for the theme of topic-c +------------ + +And then + +------------ + $ git checkout master + $ git pull --ff-only +------------ + +would grab `X`, `Y` and `Z` from the upstream and advance your master +branch: + +------------ + C0--C1--C2 topic-c + / + ---o---o---A---X---Y---Z master + \ + B0--B1--B2 topic-b +------------ + +And then you would merge these two branches separately: + +------------ + $ git merge topic-b + $ git merge topic-c +------------ + +to result in + +------------ + C0--C1---------C2 + / \ + ---o---o---A---X---Y---Z---M---N + \ / + B0--B1-----B2 +------------ + +and push it back to the central repository. + +It is very much possible that while you are merging topic-b and +topic-c, somebody again advanced the history in the central repository +to put `W` on top of `Z`, and make your `git push` fail. + +In such a case, you would rewind to discard `M` and `N`, update the +tip of your 'master' again and redo the two merges: + +------------ + $ git reset --hard origin/master + $ git pull --ff-only + $ git merge topic-b + $ git merge topic-c +------------ + +The procedure will result in a history that looks like this: + +------------ + C0--C1--------------C2 + / \ + ---o---o---A---X---Y---Z---W---M'--N' + \ / + B0--B1---------B2 +------------ + +See also http://git-blame.blogspot.com/2013/09/fun-with-first-parent-history.html
diff --git a/howto/setup-git-server-over-http.html b/howto/setup-git-server-over-http.html index e1784ee..2f4900a 100644 --- a/howto/setup-git-server-over-http.html +++ b/howto/setup-git-server-over-http.html
@@ -968,7 +968,7 @@ <div class="content"> <pre><tt>Most tests should pass.</tt></pre> </div></div> -<div class="paragraph"><p>A command line tool to test WebDAV is cadaver. If you prefer GUIs, for +<div class="paragraph"><p>A command-line tool to test WebDAV is cadaver. If you prefer GUIs, for example, konqueror can open WebDAV URLs as "webdav://…" or "webdavs://…".</p></div> <div class="paragraph"><p>If you’re into Windows, from XP onwards Internet Explorer supports @@ -1071,7 +1071,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2014-05-20 16:23:14 PDT +Last updated 2014-06-06 12:15:48 PDT </div> </div> </body>
diff --git a/howto/setup-git-server-over-http.txt b/howto/setup-git-server-over-http.txt index 6de4f3c..f44e5e9 100644 --- a/howto/setup-git-server-over-http.txt +++ b/howto/setup-git-server-over-http.txt
@@ -181,7 +181,7 @@ Most tests should pass. -A command line tool to test WebDAV is cadaver. If you prefer GUIs, for +A command-line tool to test WebDAV is cadaver. If you prefer GUIs, for example, konqueror can open WebDAV URLs as "webdav://..." or "webdavs://...".
diff --git a/revisions.txt b/revisions.txt index 5a286d0..0796118 100644 --- a/revisions.txt +++ b/revisions.txt
@@ -94,7 +94,9 @@ '<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: The suffix '@\{upstream\}' to a branchname (short form '<branchname>@\{u\}') refers to the branch that the branch specified by branchname is set to build on - top of. A missing branchname defaults to the current one. + top of (configured with `branch.<name>.remote` and + `branch.<name>.merge`). A missing branchname defaults to the + current one. '<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0':: A suffix '{caret}' to a revision parameter means the first parent of diff --git a/technical/http-protocol.html b/technical/http-protocol.html index 6890ff8..3c771ba 100644 --- a/technical/http-protocol.html +++ b/technical/http-protocol.html
@@ -1102,7 +1102,7 @@ C: 0000</tt></pre> </div></div> <div class="paragraph"><p>The stream is organized into "commands", with each command -appearing by itself in a pkt-line. Within a command line +appearing by itself in a pkt-line. Within a command line, the text leading up to the first space is the command name, and the remainder of the line to the first LF is the value. Command lines are terminated with an LF as the last byte of @@ -1237,7 +1237,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2014-03-14 14:59:49 PDT +Last updated 2014-06-06 12:15:38 PDT </div> </div> </body>
diff --git a/technical/http-protocol.txt b/technical/http-protocol.txt index 20525d9..59be59b 100644 --- a/technical/http-protocol.txt +++ b/technical/http-protocol.txt
@@ -374,7 +374,7 @@ C: 0000 The stream is organized into "commands", with each command -appearing by itself in a pkt-line. Within a command line +appearing by itself in a pkt-line. Within a command line, the text leading up to the first space is the command name, and the remainder of the line to the first LF is the value. Command lines are terminated with an LF as the last byte of
diff --git a/user-manual.html b/user-manual.html index 837d86d..c695a52 100644 --- a/user-manual.html +++ b/user-manual.html
@@ -1,5 +1,5 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Git User Manual</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="article" title="Git User Manual"><div class="titlepage"><div><div><h2 class="title"><a name="idp101856"></a>Git User Manual</h2></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#repositories-and-branches">Repositories and Branches</a></span></dt><dd><dl><dt><span class="section"><a href="#how-to-get-a-git-repository">How to get a Git repository</a></span></dt><dt><span class="section"><a href="#how-to-check-out">How to check out a different version of a project</a></span></dt><dt><span class="section"><a href="#understanding-commits">Understanding History: Commits</a></span></dt><dt><span class="section"><a href="#manipulating-branches">Manipulating branches</a></span></dt><dt><span class="section"><a href="#detached-head">Examining an old version without creating a new branch</a></span></dt><dt><span class="section"><a href="#examining-remote-branches">Examining branches from a remote repository</a></span></dt><dt><span class="section"><a href="#how-git-stores-references">Naming branches, tags, and other references</a></span></dt><dt><span class="section"><a href="#Updating-a-repository-With-git-fetch">Updating a repository with git fetch</a></span></dt><dt><span class="section"><a href="#fetching-branches">Fetching branches from other repositories</a></span></dt></dl></dd><dt><span class="section"><a href="#exploring-git-history">Exploring Git history</a></span></dt><dd><dl><dt><span class="section"><a href="#using-bisect">How to use bisect to find a regression</a></span></dt><dt><span class="section"><a href="#naming-commits">Naming commits</a></span></dt><dt><span class="section"><a href="#creating-tags">Creating tags</a></span></dt><dt><span class="section"><a href="#browsing-revisions">Browsing revisions</a></span></dt><dt><span class="section"><a href="#generating-diffs">Generating diffs</a></span></dt><dt><span class="section"><a href="#viewing-old-file-versions">Viewing old file versions</a></span></dt><dt><span class="section"><a href="#history-examples">Examples</a></span></dt></dl></dd><dt><span class="section"><a href="#Developing-With-git">Developing with Git</a></span></dt><dd><dl><dt><span class="section"><a href="#telling-git-your-name">Telling Git your name</a></span></dt><dt><span class="section"><a href="#creating-a-new-repository">Creating a new repository</a></span></dt><dt><span class="section"><a href="#how-to-make-a-commit">How to make a commit</a></span></dt><dt><span class="section"><a href="#creating-good-commit-messages">Creating good commit messages</a></span></dt><dt><span class="section"><a href="#ignoring-files">Ignoring files</a></span></dt><dt><span class="section"><a href="#how-to-merge">How to merge</a></span></dt><dt><span class="section"><a href="#resolving-a-merge">Resolving a merge</a></span></dt><dt><span class="section"><a href="#undoing-a-merge">Undoing a merge</a></span></dt><dt><span class="section"><a href="#fast-forwards">Fast-forward merges</a></span></dt><dt><span class="section"><a href="#fixing-mistakes">Fixing mistakes</a></span></dt><dt><span class="section"><a href="#ensuring-good-performance">Ensuring good performance</a></span></dt><dt><span class="section"><a href="#ensuring-reliability">Ensuring reliability</a></span></dt></dl></dd><dt><span class="section"><a href="#sharing-development">Sharing development with others</a></span></dt><dd><dl><dt><span class="section"><a href="#getting-updates-With-git-pull">Getting updates with git pull</a></span></dt><dt><span class="section"><a href="#submitting-patches">Submitting patches to a project</a></span></dt><dt><span class="section"><a href="#importing-patches">Importing patches to a project</a></span></dt><dt><span class="section"><a href="#public-repositories">Public Git repositories</a></span></dt><dt><span class="section"><a href="#sharing-development-examples">Examples</a></span></dt></dl></dd><dt><span class="section"><a href="#cleaning-up-history">Rewriting history and maintaining patch series</a></span></dt><dd><dl><dt><span class="section"><a href="#patch-series">Creating the perfect patch series</a></span></dt><dt><span class="section"><a href="#using-git-rebase">Keeping a patch series up to date using git rebase</a></span></dt><dt><span class="section"><a href="#rewriting-one-commit">Rewriting a single commit</a></span></dt><dt><span class="section"><a href="#reordering-patch-series">Reordering or selecting from a patch series</a></span></dt><dt><span class="section"><a href="#interactive-rebase">Using interactive rebases</a></span></dt><dt><span class="section"><a href="#patch-series-tools">Other tools</a></span></dt><dt><span class="section"><a href="#problems-With-rewriting-history">Problems with rewriting history</a></span></dt><dt><span class="section"><a href="#bisect-merges">Why bisecting merge commits can be harder than bisecting linear history</a></span></dt></dl></dd><dt><span class="section"><a href="#advanced-branch-management">Advanced branch management</a></span></dt><dd><dl><dt><span class="section"><a href="#fetching-individual-branches">Fetching individual branches</a></span></dt><dt><span class="section"><a href="#fetch-fast-forwards">git fetch and fast-forwards</a></span></dt><dt><span class="section"><a href="#forcing-fetch">Forcing git fetch to do non-fast-forward updates</a></span></dt><dt><span class="section"><a href="#remote-branch-configuration">Configuring remote-tracking branches</a></span></dt></dl></dd><dt><span class="section"><a href="#git-concepts">Git concepts</a></span></dt><dd><dl><dt><span class="section"><a href="#the-object-database">The Object Database</a></span></dt><dt><span class="section"><a href="#the-index">The index</a></span></dt></dl></dd><dt><span class="section"><a href="#submodules">Submodules</a></span></dt><dd><dl><dt><span class="section"><a href="#_pitfalls_with_submodules">Pitfalls with submodules</a></span></dt></dl></dd><dt><span class="section"><a href="#low-level-operations">Low-level Git operations</a></span></dt><dd><dl><dt><span class="section"><a href="#object-manipulation">Object access and manipulation</a></span></dt><dt><span class="section"><a href="#the-workflow">The Workflow</a></span></dt><dt><span class="section"><a href="#examining-the-data">Examining the data</a></span></dt><dt><span class="section"><a href="#merging-multiple-trees">Merging multiple trees</a></span></dt><dt><span class="section"><a href="#merging-multiple-trees-2">Merging multiple trees, continued</a></span></dt></dl></dd><dt><span class="section"><a href="#hacking-git">Hacking Git</a></span></dt><dd><dl><dt><span class="section"><a href="#object-details">Object storage format</a></span></dt><dt><span class="section"><a href="#birdview-on-the-source-code">A birds-eye view of Git’s source code</a></span></dt></dl></dd><dt><span class="section"><a href="#glossary">Git Glossary</a></span></dt><dt><span class="appendix"><a href="#git-quick-start">A. Git Quick Reference</a></span></dt><dd><dl><dt><span class="section"><a href="#quick-creating-a-new-repository">Creating a new repository</a></span></dt><dt><span class="section"><a href="#managing-branches">Managing branches</a></span></dt><dt><span class="section"><a href="#exploring-history">Exploring history</a></span></dt><dt><span class="section"><a href="#making-changes">Making changes</a></span></dt><dt><span class="section"><a href="#merging">Merging</a></span></dt><dt><span class="section"><a href="#sharing-your-changes">Sharing your changes</a></span></dt><dt><span class="section"><a href="#repository-maintenance">Repository maintenance</a></span></dt></dl></dd><dt><span class="appendix"><a href="#todo">B. Notes and todo list for this manual</a></span></dt></dl></div><p>Git is a fast distributed revision control system.</p><p>This manual is designed to be readable by someone with basic UNIX +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Git User Manual</title><link rel="stylesheet" type="text/css" href="docbook-xsl.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="article" title="Git User Manual"><div class="titlepage"><div><div><h2 class="title"><a name="idp216640"></a>Git User Manual</h2></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#repositories-and-branches">Repositories and Branches</a></span></dt><dd><dl><dt><span class="section"><a href="#how-to-get-a-git-repository">How to get a Git repository</a></span></dt><dt><span class="section"><a href="#how-to-check-out">How to check out a different version of a project</a></span></dt><dt><span class="section"><a href="#understanding-commits">Understanding History: Commits</a></span></dt><dt><span class="section"><a href="#manipulating-branches">Manipulating branches</a></span></dt><dt><span class="section"><a href="#detached-head">Examining an old version without creating a new branch</a></span></dt><dt><span class="section"><a href="#examining-remote-branches">Examining branches from a remote repository</a></span></dt><dt><span class="section"><a href="#how-git-stores-references">Naming branches, tags, and other references</a></span></dt><dt><span class="section"><a href="#Updating-a-repository-With-git-fetch">Updating a repository with git fetch</a></span></dt><dt><span class="section"><a href="#fetching-branches">Fetching branches from other repositories</a></span></dt></dl></dd><dt><span class="section"><a href="#exploring-git-history">Exploring Git history</a></span></dt><dd><dl><dt><span class="section"><a href="#using-bisect">How to use bisect to find a regression</a></span></dt><dt><span class="section"><a href="#naming-commits">Naming commits</a></span></dt><dt><span class="section"><a href="#creating-tags">Creating tags</a></span></dt><dt><span class="section"><a href="#browsing-revisions">Browsing revisions</a></span></dt><dt><span class="section"><a href="#generating-diffs">Generating diffs</a></span></dt><dt><span class="section"><a href="#viewing-old-file-versions">Viewing old file versions</a></span></dt><dt><span class="section"><a href="#history-examples">Examples</a></span></dt></dl></dd><dt><span class="section"><a href="#Developing-With-git">Developing with Git</a></span></dt><dd><dl><dt><span class="section"><a href="#telling-git-your-name">Telling Git your name</a></span></dt><dt><span class="section"><a href="#creating-a-new-repository">Creating a new repository</a></span></dt><dt><span class="section"><a href="#how-to-make-a-commit">How to make a commit</a></span></dt><dt><span class="section"><a href="#creating-good-commit-messages">Creating good commit messages</a></span></dt><dt><span class="section"><a href="#ignoring-files">Ignoring files</a></span></dt><dt><span class="section"><a href="#how-to-merge">How to merge</a></span></dt><dt><span class="section"><a href="#resolving-a-merge">Resolving a merge</a></span></dt><dt><span class="section"><a href="#undoing-a-merge">Undoing a merge</a></span></dt><dt><span class="section"><a href="#fast-forwards">Fast-forward merges</a></span></dt><dt><span class="section"><a href="#fixing-mistakes">Fixing mistakes</a></span></dt><dt><span class="section"><a href="#ensuring-good-performance">Ensuring good performance</a></span></dt><dt><span class="section"><a href="#ensuring-reliability">Ensuring reliability</a></span></dt></dl></dd><dt><span class="section"><a href="#sharing-development">Sharing development with others</a></span></dt><dd><dl><dt><span class="section"><a href="#getting-updates-With-git-pull">Getting updates with git pull</a></span></dt><dt><span class="section"><a href="#submitting-patches">Submitting patches to a project</a></span></dt><dt><span class="section"><a href="#importing-patches">Importing patches to a project</a></span></dt><dt><span class="section"><a href="#public-repositories">Public Git repositories</a></span></dt><dt><span class="section"><a href="#sharing-development-examples">Examples</a></span></dt></dl></dd><dt><span class="section"><a href="#cleaning-up-history">Rewriting history and maintaining patch series</a></span></dt><dd><dl><dt><span class="section"><a href="#patch-series">Creating the perfect patch series</a></span></dt><dt><span class="section"><a href="#using-git-rebase">Keeping a patch series up to date using git rebase</a></span></dt><dt><span class="section"><a href="#rewriting-one-commit">Rewriting a single commit</a></span></dt><dt><span class="section"><a href="#reordering-patch-series">Reordering or selecting from a patch series</a></span></dt><dt><span class="section"><a href="#interactive-rebase">Using interactive rebases</a></span></dt><dt><span class="section"><a href="#patch-series-tools">Other tools</a></span></dt><dt><span class="section"><a href="#problems-With-rewriting-history">Problems with rewriting history</a></span></dt><dt><span class="section"><a href="#bisect-merges">Why bisecting merge commits can be harder than bisecting linear history</a></span></dt></dl></dd><dt><span class="section"><a href="#advanced-branch-management">Advanced branch management</a></span></dt><dd><dl><dt><span class="section"><a href="#fetching-individual-branches">Fetching individual branches</a></span></dt><dt><span class="section"><a href="#fetch-fast-forwards">git fetch and fast-forwards</a></span></dt><dt><span class="section"><a href="#forcing-fetch">Forcing git fetch to do non-fast-forward updates</a></span></dt><dt><span class="section"><a href="#remote-branch-configuration">Configuring remote-tracking branches</a></span></dt></dl></dd><dt><span class="section"><a href="#git-concepts">Git concepts</a></span></dt><dd><dl><dt><span class="section"><a href="#the-object-database">The Object Database</a></span></dt><dt><span class="section"><a href="#the-index">The index</a></span></dt></dl></dd><dt><span class="section"><a href="#submodules">Submodules</a></span></dt><dd><dl><dt><span class="section"><a href="#_pitfalls_with_submodules">Pitfalls with submodules</a></span></dt></dl></dd><dt><span class="section"><a href="#low-level-operations">Low-level Git operations</a></span></dt><dd><dl><dt><span class="section"><a href="#object-manipulation">Object access and manipulation</a></span></dt><dt><span class="section"><a href="#the-workflow">The Workflow</a></span></dt><dt><span class="section"><a href="#examining-the-data">Examining the data</a></span></dt><dt><span class="section"><a href="#merging-multiple-trees">Merging multiple trees</a></span></dt><dt><span class="section"><a href="#merging-multiple-trees-2">Merging multiple trees, continued</a></span></dt></dl></dd><dt><span class="section"><a href="#hacking-git">Hacking Git</a></span></dt><dd><dl><dt><span class="section"><a href="#object-details">Object storage format</a></span></dt><dt><span class="section"><a href="#birdview-on-the-source-code">A birds-eye view of Git’s source code</a></span></dt></dl></dd><dt><span class="section"><a href="#glossary">Git Glossary</a></span></dt><dt><span class="appendix"><a href="#git-quick-start">A. Git Quick Reference</a></span></dt><dd><dl><dt><span class="section"><a href="#quick-creating-a-new-repository">Creating a new repository</a></span></dt><dt><span class="section"><a href="#managing-branches">Managing branches</a></span></dt><dt><span class="section"><a href="#exploring-history">Exploring history</a></span></dt><dt><span class="section"><a href="#making-changes">Making changes</a></span></dt><dt><span class="section"><a href="#merging">Merging</a></span></dt><dt><span class="section"><a href="#sharing-your-changes">Sharing your changes</a></span></dt><dt><span class="section"><a href="#repository-maintenance">Repository maintenance</a></span></dt></dl></dd><dt><span class="appendix"><a href="#todo">B. Notes and todo list for this manual</a></span></dt></dl></div><p>Git is a fast distributed revision control system.</p><p>This manual is designed to be readable by someone with basic UNIX command-line skills, but no previous knowledge of Git.</p><p><a class="xref" href="#repositories-and-branches" title="Repositories and Branches">the section called “Repositories and Branches”</a> and <a class="xref" href="#exploring-git-history" title="Exploring Git history">the section called “Exploring Git history”</a> explain how to fetch and study a project using git—read these chapters to learn how to build and test a particular version of a software project, search for @@ -1869,9 +1869,9 @@ called by the script.</p><p>Most of what <code class="literal">git rev-list</code> did is contained in <code class="literal">revision.c</code> and <code class="literal">revision.h</code>. It wraps the options in a struct named <code class="literal">rev_info</code>, which controls how and what revisions are walked, and more.</p><p>The original job of <code class="literal">git rev-parse</code> is now taken by the function -<code class="literal">setup_revisions()</code>, which parses the revisions and the common command line +<code class="literal">setup_revisions()</code>, which parses the revisions and the common command-line options for the revision walker. This information is stored in the struct -<code class="literal">rev_info</code> for later consumption. You can do your own command line option +<code class="literal">rev_info</code> for later consumption. You can do your own command-line option parsing after calling <code class="literal">setup_revisions()</code>. After that, you have to call <code class="literal">prepare_revision_walk()</code> for initialization, and then you can get the commits one by one with the function <code class="literal">get_revision()</code>.</p><p>If you are interested in more details of the revision walking process,
diff --git a/user-manual.txt b/user-manual.txt index 022e74e..d33f884 100644 --- a/user-manual.txt +++ b/user-manual.txt
@@ -4231,9 +4231,9 @@ controls how and what revisions are walked, and more. The original job of `git rev-parse` is now taken by the function -`setup_revisions()`, which parses the revisions and the common command line +`setup_revisions()`, which parses the revisions and the common command-line options for the revision walker. This information is stored in the struct -`rev_info` for later consumption. You can do your own command line option +`rev_info` for later consumption. You can do your own command-line option parsing after calling `setup_revisions()`. After that, you have to call `prepare_revision_walk()` for initialization, and then you can get the commits one by one with the function `get_revision()`.
